home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / dev / pfs.man < prev    next >
Text File  |  1989-02-09  |  16KB  |  377 lines
  1. '\" Copyright 1989 Regents of the University of California
  2. '\" Permission to use, copy, modify, and distribute this
  3. '\" documentation for any purpose and without fee is hereby
  4. '\" granted, provided that this notice appears in all copies.
  5. '\" The University of California makes no representations about
  6. '\" the suitability of this material for any purpose.  It is
  7. '\" provided "as is" without express or implied warranty.
  8. '\" 
  9. '\" $Header: /sprite/lib/forms/RCS/proto.man,v 1.5 89/01/27 08:36:02 ouster Exp $ SPRITE (Berkeley)
  10. '/" 
  11. .so \*(]ltmac.sprite
  12. .HS PFS dev
  13. .BS
  14. .SH NAME
  15. Pseudo-file-systems \- File systems implemented by user-level server processes.
  16. .BE
  17.  
  18. .SH INTRODUCTION
  19. .PP
  20. A pseudo-file-system is a part of the distributed file system that
  21. is implemented by a user-level server process as opposed to
  22. parts of the file system that correspond to real disks (local or remote)
  23. controlled by Sprite kernels.  The pseudo-file-system has its own
  24. prefix and is transparently integrated in to the global file hierarchy.
  25. Files in a pseudo-file-system are named and accessed with the same
  26. system calls as regular files (or devices).
  27. .PP
  28. This document describes the raw kernel interface used by pseudo-file-system
  29. servers.  The interface is a superset of the pseudo-device interface
  30. that is described in the \fBpdev\fP devices man page.
  31. There is also
  32. a \fBPfs\fP library package that takes care of most of the details
  33. of the interface and provides an easy-to-use call-back interface.
  34. .SH REQUEST-RESPONSE STREAMS
  35. .PP
  36. The operating system forwards operations on the pseudo-file-system up
  37. to the user-level server process using the pseudo-device request response
  38. protocol.  This protocol is described in detail
  39. in the \fBpdev\fP man page.  When the
  40. server starts up it gets a \fInaming stream\fP that is used to
  41. forward naming operations like \fBopen\fP, \fBremove\fP, \fBmkdir\fP,
  42. and \fBrename\fP.  In response to an \fBopen\fP the server can
  43. create a new \fIservice stream\fP to handle subsequent  I/O operations
  44. on the open file.  This service stream is exactly like a pseudo-device
  45. service stream, except for two additional operations,
  46. PDEV_GET_ATTR (for \fBfstat\fP) and PDEV_SET_ATTR (for \fBfchown\fP
  47. and \fBfchmod\fP).  Thus the server ultimately has several
  48. request response streams.  One naming stream and several service
  49. streams, one for each open file.
  50. .SH SERVER INITIALIZATION
  51. .PP
  52. The pseudo-file-system is activated by opening its prefix with
  53. the O_MASTER flag.  There must be a remote link for the prefix
  54. or the open will fail.  (Use \fBln -r\fP to make remote links.)
  55. The prefix can be nested arbitrarily in the file system.
  56. The result of the open is a streamID for the naming stream.
  57. The IOC_PDEV_SET_BUF I/O Control has to be made on this stream
  58. before the request response protocol can be used.
  59. After this is done the naming stream is used exactly like
  60. a pseudo-device service stream,
  61. except that different (naming) operations appear in the request buffer.
  62. .PP
  63. Only one server per prefix is allowed.  If the prefix corresponds to
  64. a regular part of the file system,
  65. or there is already a user-level server for it,
  66. or there is no remote link,
  67. then the open will fail.
  68. .PP
  69. The prefix is exported throughout the network,
  70. unless the O_EXCLUSIVE flag is passed to \fBopen\fP.
  71. The kernel takes care of exporting the prefix;
  72. the server has to take no special action.
  73. The existence of the corresponding remote link means
  74. that the kernel's name lookup algorithm will automatically find
  75. the prefix for the pseudo-file-system and locate the server.
  76. .SH NAMING OPERATIONS
  77. .PP
  78. The request messages in the naming stream have the same header as
  79. pseudo-device requests, but different operation codes
  80. and operation-specific parameters.
  81. Note that the magic number in the request header is
  82. PFS_REQUEST_MAGIC. 
  83. .ta 3.0i
  84. .DS
  85.  
  86. typedef struct {
  87.     unsigned int magic;    /* PDEV_REQUEST_MAGIC or PFS_REQUEST_MAGIC */
  88.     Pdev_Op operation;    /* What action is requested. */
  89.     int messageSize;    /* The complete size of the request header
  90.      * plus data, plus padding for alignment */
  91.     int requestSize;    /* Size of data following this header */
  92.     int replySize;    /* Max size of the reply data expected. */
  93.     int dataOffset;    /* Offset of data from start of header */
  94. } Pdev_RequestHdr;
  95.  
  96. typedef struct {
  97.     Pdev_RequestHdr hdr;    /* with PFS_REQUEST_MAGIC */
  98.     union {    /* Additional parameters to the operation. */
  99.         FsOpenArgs    open;
  100.         FsOpenArgs    getAttr;
  101.         FsOpenArgs    setAttr;
  102.         FsMakeDeviceArgs    makeDevice;
  103.         FsOpenArgs    makeDir;
  104.         FsLookupArgs    remove;
  105.         FsLookupArgs    removeDir;
  106.         Fs2PathParams    rename;
  107.         Fs2PathParams    hardLink;
  108.         FsOpenArgs    symLink;
  109.     } param;
  110.     /*
  111.      * Data follows
  112.      */
  113. } Pfs_Request;
  114. .DS
  115. .PP
  116. The operation specific parameters are
  117. described below along with the operations they are used with.
  118. These are defined in <dev/pfs.h>.
  119. All the operation-specific parameters include
  120. a \fBprefixID\fP that is a fileID for the starting point of the pathname
  121. involved in the naming operation.  This corresponds to the
  122. pseudo-file-system prefix if the original pathname was absolute,
  123. or it corresponds to the process's current working directory
  124. if the original pathname was relative.  In either case the
  125. pathname given to the server is relative.
  126. The fileID for the pseudo-file-system prefix has all zero fields,
  127. unless it has been reset with the IOC_PFS_SET_ID call.
  128. The fileID for the current directory is set when the
  129. current directory is opened by the process.
  130. This is described
  131. in the section below on opening files.
  132. .PP
  133. In the request-response protocol some data may follow each request
  134. message header and operation-specific parameters.
  135. This data is simply the pathname for the
  136. following pseudo-file-system operations:
  137. PFS_OPEN, PFS_GET_ATTR, PFS_MAKE_DEVICE, PFS_MAKE_DIR, PFS_REMOVE,
  138. and PFS_REMOVE_DIR.  The other operations,
  139. PFS_SET_ATTR, PFS_RENAME, and PFS_HARD_LINK have their
  140. data areas described below.
  141. .PP
  142. For all the operations the exact location and size of the data
  143. is specified by the \fBdataOffset\fP and \fBrequestSize\fP
  144. fields in the request message header.
  145. .SH REPLYING TO REQUESTS
  146. .PP
  147. Naming requests are replied to just like regular pseudo-device
  148. requests using IOC_PDEV_REPLY.  However, with naming operations
  149. there is the possiblity of \fIpathname redirection\fP.
  150. If the pathname leaves the part of the file hierarchy controlled
  151. by the pseudo-file-system server then it cannot complete the naming operation.
  152. Instead, it must return the remaining pathname as the reply data
  153. along with the special reply status FS_LOOKUP_REDIRECT.
  154. There are two formats for the returned pathname:
  155. .DS
  156. .ta 3.0i
  157. typedef struct FsRedirectInfo {
  158.     int    prefixLength;    /* The length of the prefix embedded in
  159.      * fileName.  This is used when a server hits
  160.      * a remote link and has to return a new file
  161.      * name plus an indication of a new prefix.
  162.      * Zero means no embedded prefix. */
  163.     char fileName[FS_MAX_PATH_NAME_LENGTH];
  164.     /* A new file name.  Returned
  165.      * from the server when its lookup is about
  166.      * to leave its domain. */
  167. } FsRedirectInfo;
  168.  
  169. typedef struct Fs2PathRedirectInfo {
  170.     int name1ErrorP;    /* TRUE if redirection applies
  171.      * to the first pathname, FALSE if the error
  172.      * applies to second pathname, or no error */
  173.     int    prefixLength;
  174.     char fileName[FS_MAX_PATH_NAME_LENGTH];
  175. } Fs2PathRedirectInfo;
  176. .DE
  177. .PP
  178. Pathname redirection can occur in three cases:
  179. a symbolic link to an absolute pathname is encountered,
  180. a remote link is encountered,
  181. a ``..'' pathname component is encountered that would
  182. take the pathname out the top of the pseudo-file-system.
  183. If an absolute symbolic link or a remote link is encountered the
  184. server should expand the link and then return the new
  185. absolute pathname.  If it was a remote link then the link
  186. contents identify a prefix.  Its length should be set in 
  187. the \fBprefixLength\fP field.  If it is not a remote link then
  188. the \fBprefixLength\fR field should be set to zero to indicate no
  189. prefix information.  If a ``..'' component corresponds to
  190. a directory outside the pseudo-file-system then the remaining
  191. pathname, including the offending ``..'' component,
  192. should be returned.  The \fBprefixLength\fP field should again be zero.
  193. .PP
  194. The PFS_RENAME and PFS_HARD_LINK operations may have redirection occur
  195. on either pathname.  \fBFs2PathRedirectInfo\fP contains a
  196. field \fBname1ErrorP\fP that is used to indicate what pathname
  197. caused a redirection.
  198. Also, these operations may be invoked even if the second pathname
  199. is not part of the pseudo-file-system.  This situation is indicated
  200. in the operation-specific parameters by a \fBprefixID2.type\fP value of -1.
  201. The pseudo-file-system server is invoked in this case to see if
  202. the first pathname will redirect out of the pseudo-file-system
  203. and perhaps end up with the same server as the second pathname.
  204. If redirection of the first name does not occur and
  205. the second pathname is not in the pseudo-file-system then the
  206. operation cannot succeed and FS_CROSS_DOMAIN_OPERATION
  207. should be returned.
  208. .SH PFS_OPEN
  209. .DS
  210. typedef struct FsOpenArgs {
  211.     Fs_FileID prefixID;    /* File ID from prefix handle */
  212.     Fs_FileID rootID;    /* File ID of root.
  213.      * Used to trap ".." past the root. */
  214.     int useFlags;    /* Flags defined in fs.h */
  215.     int permissions;    /* Permission bits for created files.  Already
  216.      * reflects per-process permission mask */
  217.     int type;    /* Used to contrain open to a specific type */
  218.     int clientID;    /* Host ID of client doing the open */
  219.     Fs_UserIDs id;    /* User and group IDs */
  220. } FsOpenArgs;
  221. .DE
  222. .PP
  223. The PFS_OPEN operation is used to open a file in the pseudo-file-system.
  224. The \fBprefixID\fR has been explained above.
  225. The \fBrootID\fR is unused for pseudo-file-systems.
  226. The \fBuseFlags\fR are those passed to the \fBopen\fP system call.
  227. The \fBpermissions\fP are used when creating new files
  228. and they already reflect a per-process mode mask.
  229. The \fBtype\fP is used to contrain the open to succeed only
  230. for certain types of files.
  231. Possible values are FS_FILE, which means any type is acceptable,
  232. FS_DIRECTORY, and FS_SYMBOLIC_LINK.
  233. The \fBclientID\fP is the Sprite hostID of the host the opening
  234. process is running on.
  235. The \fBid\fP structure contains the user and group IDs of the opening process.
  236. .PP
  237. When a file in the pseudo-file-system is opened the
  238. server can either handle all subsequent operations itself,
  239. or it can open a regular file and pass this open file
  240. off to the opening process.
  241. Both of these operations are done \fIinstead\fP of replying
  242. with IOC_PDEV_REPLY, which should only be used for error replies.
  243. .PP
  244. IOC_PFS_OPEN is used to create a new pseudo-device connection
  245. for the file being opened.  The input parameters of this
  246. call are the FsFileID for the connection,
  247. and the return parametmer of the call is the open file descriptor
  248. for the service stream.  The new service stream is exactly like
  249. a pseudo-device service stream, and all I/O operations on the
  250. open file will be forwarded to the server using this service stream.
  251. The FsFileID is kept with the kernel state for the open file.
  252. If the open file is a process's current directory,
  253. then the FsFileID will be passed to the server as the
  254. prefixID part of the naming parameters.
  255. .PP
  256. IOC_PFS_PASS_STREAM is used to pass an already open file back to the
  257. opening process.  If this is done then the kernel handles all
  258. subsequent operations
  259. on the open file.  The pseudo-device server is only notified
  260. when the file is closed (maybe, if that seems implementable.)
  261. .SH PFS_GET_ATTR
  262. .PP
  263. The PFS_GET_ATTR operation is used to get the attributes
  264. of a file in the pseudo-file-system given its name.
  265. It has the same operation specific parameters as PFS_OPEN.
  266. The reply data for this call should be an Fs_Attributes structure.
  267. .SH PFS_SET_ATTR
  268. .DS
  269. typedef struct {
  270.     Fs_Attributes    attr;        /* Attribute values */
  271.     int            flags;        /* Indicates which attributes to set */
  272.     int            nameLength;    /* Number of bytes in name */
  273.     char        name[4];    /* Actually larger */
  274. } Pfs_SetAttrData;
  275. .DE
  276. .PP
  277. The PFS_SET_ATTR operation is used to set certain attributes
  278. of a file in the pseudo-file-system given its name.
  279. The operation specific parameters are the same as those for
  280. the PFS_OPEN operation, except that there are additional
  281. paramaters passed as data following this header.  The format
  282. of the data is defined above as type \fBPfs_SetAttrData\fP.
  283. This includes the new attributes for the file,
  284. and a flags field that indicates which attributes to set.
  285. The value of \fBflags\fR is an or'd combination of
  286. \fBFS_SET_TIMES\fR, \fBFS_SET_MODE\fR, \fBFS_SET_OWNER\fR,
  287. \fBFS_SET_FILE_TYPE\fR, \fBFS_SET_DEVICE\fR.
  288. .SH PFS_MAKE_DEVICE
  289. .DS
  290. typedef struct FsMakeDeviceArgs {
  291.     Fs_FileID prefixID;    /* FileID of the prefix */
  292.     Fs_FileID rootID;    /* FileID of the root */
  293.     Fs_Device device;    /* Identifies the device */
  294.     int permissions;    /* Permissions already reflect per-process mask */
  295.     Fs_UserIDs id;
  296.     int clientID;
  297. } FsMakeDeviceArgs;
  298. .DE
  299. .PP
  300. The PFS_MAKE_DEVICE operation is used to create a special device
  301. file in the pseudo-file-system.  The \fBFsMakeDeviceArgs\fP are similar to the
  302. \fBFsOpenArgs\fP with some addition information about the device.
  303. .SH PFS_MAKE_DIR
  304. .PP
  305. The PFS_MAKE_DIR operation is used to create a directory in the
  306. pseudo-file-system.  It uses the same operation specific parameters
  307. as the PFS_OPEN operation.
  308. .SH PFS_REMOVE
  309. .DS
  310. typedef struct FsLookupArgs {
  311.     Fs_FileID prefixID;    /* FileID of the prefix */
  312.     Fs_FileID rootID;    /* FileID of the root */
  313.     int useFlags;    /* not used */
  314.     Fs_UserIDs id;    /* User and group IDs */
  315.     int clientID;    /* Needed to expand $MACHINE */
  316. } FsLookupArgs;
  317. .DE
  318. .PP
  319. The PFS_REMOVE operation is used to remove a file from the pseudo-file-system.
  320. Its operation specific parameters are a simplified version of
  321. the parameters used for PFS_OPEN.
  322. .SH PFS_REMOVE_DIR
  323. .PP
  324. The PFS_REMOVE_DIR operation is used to remove a directory from
  325. the pseudo-file-system.  The server should guard against removing
  326. non-empty directories.
  327. .SH PFS_RENAME
  328. .DS
  329. typedef struct Fs2PathParams {
  330.     FsLookupArgs    lookup;    /* Standard lookup arguments */
  331.     Fs_FileID    prefixID2;    /* Prefix ID of second pathname */
  332. } Fs2PathParams;
  333. .DE
  334. .PP
  335. The PFS_RENAME operation is used to change the name of a file
  336. in the pseudo-file-system.  The operation-specific parameters
  337. include the prefixID for the second pathname.  The data following
  338. the header contains two null-terminated
  339. relative pathnames in the following format:
  340. .DS
  341. typedef struct Fs2PathData {
  342.     char        path1[FS_MAX_PATH_NAME_LENGTH];
  343.     char        path2[FS_MAX_PATH_NAME_LENGTH];
  344. } Fs2PathData;
  345. .DE
  346. .SH PFS_HARD_LINK
  347. .PP
  348. The PFS_HARD_LINK operation is used to create another name
  349. for a existing file in the pseudo-file-system.  It has the
  350. same operation-specifc parameters and data format
  351. as the PFS_RENAME command.
  352. .SH PFS_SYM_LINK
  353. .PP
  354. The PFS_SYM_LINK operation is used to create either a symblic link
  355. or a remote link in
  356. the pseudo-file-system.
  357. The operation specific parameters are the same as for PFS_OPEN,
  358. and the data contains two pathnames in the \fBFs2PathData\fP structure.
  359. The first name is the name of the link file,
  360. and the second name is the name for the link value.
  361. The \fBtype\fP field in the \fBFsOpenArgs\fP structure determines
  362. if it should be a remote link or a regular symbolic link.
  363. .SH NOTICES
  364. .PP
  365. IOC_PFS_PASS_STREAM is unimplemented, yet.
  366. .PP
  367. PFS_SYM_LINK is unimplemented, yet.  Instead, symbolic links are
  368. created by using PFS_OPEN and then PDEV_WRITE to write the link value.
  369. .PP
  370. A new operation, PFS_FS_INFO, will be added to return file system
  371. information like free space.
  372. .SH SEE ALSO
  373. Pfs, Pdev, pdev
  374. .SH KEYWORDS
  375. server, pseudo-device
  376.  
  377.